Fix the money Fix the world

Overview

This Pull Request integrates Bull Mesh, a resilient offline communication layer allowing signed Bitcoin transactions to be broadcast without an Internet connection. The system leverages Bluetooth Low Energy (BLE) to propagate transactions to nearby peers (Relays), who then forward them to the Bitcoin Mempool.

Technical Architecture

The implementation utilizes a three-tier architecture designed to overcome standard BLE data limitations and OS-level background execution constraints.

1. Fragmentation Protocol (MeshProtocol)

To bypass the standard BLE MTU limit (~23-512 bytes), a custom application-layer fragmentation protocol has been implemented in lib/core/mesh/mesh_protocol.dart.

• Payload Segmentation: Transactions are serialized into raw Hex and split into chunks of 500 bytes.
• Header Structure: Each chunk is prefixed with a 2-byte header [TotalChunks (1B) | ChunkIndex (1B)].
• Capacity: Supports payloads up to ~127KB (255 chunks), sufficient for large CoinJoin or Multisig transactions.
• Reassembly: The receiver utilizes a buffer map Map<int, Uint8List> to accumulate chunks out-of-order, reassembling the full payload only when map.length == totalChunks.

2. Persistent Background Services (MeshBackgroundService)

To ensure high availability of Relays, the system implements OS-specific background persistence strategies.

• Android (Foreground Service):
  • Utilizes flutter_background_service to spawn a dedicated Isolate.
  • Promotes the process to a Foreground Service with a pinned notification ("Sentinel Mode").
  • Ensures the BLE scanning process is not terminated by the Android Low Memory Killer (LMK).
• iOS (Background Modes):
  • Configured with bluetooth-central, bluetooth-peripheral, and fetch capabilities in Info.plist.
  • Operates on a "Best Effort" execution model compliant with iOS BGAppRefresh policies.
• Isolate Communication Bridge:
  • Implements a bi-directional event channel to safely marshal data between the Background Isolate (Scanner) and the Main UI Isolate.
  • Methods injectIncomingTx and injectDownloadProgress in MeshService handle the safe ingestion of background events.

3. Transmission Strategy: "Looping Beacon"

The Sender implements a cyclic transmission strategy to maximize connection probability without strict handshakes:

• Cyclic Advertising: The sender iterates through the transaction chunks indefinitely (1->2->3...1->2->3).
• Asynchronous Connection: Receivers can initiate connection at any point in the cycle.
• Latency Tolerance: Duplicate chunks are discarded; missing chunks are awaited in the next cycle.

User Interface Implementation

Sender: Adaptive Radar (MeshSignalAnimation)

• State Machine: Visualizes three distinct states:
  1. Scanning: Low-frequency pulse animation.
  2. Handshake: High-frequency "Lock-on" animation upon peer connection.
  3. Transmission: Deterministic progress ring driven by the uploadProgressNotifier.

Receiver: Reactive Dashboard (MeshRelayDashboard)

• Event-Driven UI: The dashboard is triggered automatically via downloadProgressNotifier (start of transmission) or incomingTransactions stream (completion).
• Progress Visualization: Displays real-time byte reassembly status.
• Verification: Shows the computed TxID only after the reassembled payload passes Hex validation.

Security & Validation

• Input Sanitization: Incoming payloads undergo strict RegEx validation (^[0-9a-fA-F]+$) before any interaction with the BDK (Bitcoin Dev Kit).
• Sandboxing: The Mesh service operates completely independently of the wallet's key storage. It acts strictly as a data transport layer for pre-signed raw transactions.

Verification

Unit Testing

• test/core/mesh/mesh_protocol_test.dart:
  • Logic: Validates the splitting and rejoining of Uint8List payloads.
  • Edge Cases: Verifies handling of out-of-order chunk arrival and partial datasets.

Manual Verification

• Throughput: Verified successful transmission of 2KB+ transaction payloads.
• Persistence: Confirmed Android Service persistence across app minimization and device sleep states.
• Interoperability: Validated communication between Android and iOS devices.

File Manifest

• Protocol: lib/core/mesh/mesh_protocol.dart
• Service: lib/core/mesh/mesh_service.dart, lib/core/mesh/mesh_background_service.dart
• UI: lib/features/broadcast_signed_tx/presentation/widgets/
• Config: android/app/src/main/AndroidManifest.xml, pubspec.yaml